% Copyright 2019 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


% \section{Providing Data for a Data Visualization}
\section{为数据可视化提供数据}
\label{section-dv-formats}

% \subsection{Overview}
\subsection{概述}

% The data visualization system needs a stream of data points as input. These data points can be directly generated by repeatedly calling the |\pgfdatapoint| command, but usually data is available in some special (text) format and one would like to visualize this data. The present section explains how data in some specific format can be fed to the data visualization system.

数据可视化系统需要数据点流作为输入。这些数据点可以通过重复调用 |\pgfdatapoint| 命令直接生成，但是通常可以使用一些特殊（文本）格式的数据，人们希望将这些数据可视化。本节解释如何将某些特定格式的数据提供给数据可视化系统。

% This section starts with an explanation of the main concepts. Then, the standard formats are listed in the reference section. It is also possible to define new formats, but this an advanced concept which requires an understanding of some of the internals of the parsing mechanism, explained in Section~\ref{section-dv-parsing}, and the usage of a rather low-level command, explained in Section~\ref{section-dv-declaring-formats}.

本节首先解释主要概念。然后，参考部分列出了标准格式。也可以定义新的格式，但这是一个高级概念，需要理解解析机制的一些内部内容，将在第\ref{section-dv-parsing}一节中解释，以及使用一个相当低级的命令，将在第\ref{section-dv-declarcing-formats}节中解释。


% \subsection{Concepts}
\subsection{概念}

% For the purposes of this section, let call a \emph{data format} some standardized way of writing down a list of data points. A simple example of a data format is the \textsc{csv} format (the acronym stands for \emph{comma separated values}), where each line contains a data point, specified by values separated by commas. A different format is the \emph{key--value format}, where data points are specified by lists of key--value pairs. A far more complex format is the \textsc{pdb}-format used by the protein database to describe molecules.

出于本节的目的，让我们调用\emph{数据格式}的一些标准化的方法来记录数据点列表。数据格式的一个简单例子是\textsc{csv}格式（首字母缩写代表\emph{逗号分隔值}），其中每行包含一个数据点，由逗号分隔的值指定。另一种格式是\emph{键值格式}，其中数据点由键值对列表指定。一个更复杂的格式是\textsc{pdb}格式，用蛋白质数据库来描述分子。

% The data visualization system does not use any specific format. Instead, whenever data is read by the data visualization system, you must specify a format parser (or it is chosen automatically for you). It is the job of the parser to read (parse) the data lines and to turn them into data points, that is, to setup appropriate subkeys of |/data point/|.

数据可视化系统不使用任何特定的格式。相反，当数据可视化系统读取数据时，必须指定格式解析器（或者自动为您选择）。解析器的工作是读取（解析）数据行并将它们转换为数据点，即设置适当的 |/data point/| 的子键。

% To give a concrete example, suppose a file contains the following lines:

举一个具体的例子，假设一个文件包含以下几行：
%
\begin{codeexample}[code only]
x, y, z
0, 0, 0
1, 1, 0
1, 1, 0.5
0, 1, 0.5
\end{codeexample}
%
% This file is in the \textsc{csv}-format. This format can be read by the |table| parser (which is called thus, rather than ``|csv|'', since it can also read files in which the columns are separated by, say, a semicolon or a space). The |table| format will then read the data and for each line of the data, except for the headline of course, it will produce one data point. For instance, for the last data point the key |/data point/x| will be set to |0|, the key |/data point/y| will be set to |1|, and the key |/data point/z| will be set to |0.5|.
%
此文件为\textsc{csv}格式。这种格式可以被 |table| 解析器读取（之所以不称为``|csv|''，是因为它还可以读取列之间用分号或空格隔开的文件）。然后，|table| 格式将读取数据，对于数据的每一行（当然除了标题之外），它将生成一个数据点。例如，对于最后一个数据点，关键字 |/data point/x| 将被设置为 |0|，关键字 |/data point/y| 将被设置为 |1|，关键字 |/data point/z| 将被设置为 |0.5|。

% All parsers are basically line-oriented. This means that, normally, each line in the input data should contain one data point. This rule may not always apply, for instance empty lines are typically ignored and sometimes a data point may span several lines, but deviating from this ``one data point per line'' rule makes parsers harder to program.

所有解析器基本上都是面向行的。这意味着，通常输入数据中的每一行应该包含一个数据点。这个规则可能并不总是适用，例如通常会忽略空行，有时一个数据点可能跨越几行，但是偏离``每行一个数据点''的规则会使解析器更难编程。


% \subsection{Reference: Built-In Formats}
\subsection{参考：内置格式}

% The following format is the default format, when no |format=...| is specified.

下面的格式是默认格式，是当没有 |format=...| 确定的格式。

\begin{dataformat}{table}
    % This format is used to parse data that is formatted in the following manner: Basically, each line consists of \emph{values} that are separated by a \emph{separator} like a comma or a space. The values are stored in different \emph{attributes}, that is, subkeys of |/data point| like |/data point/x|. In order to decide which attribute is chosen for a give value, the headline is important. This is the first non-empty line of a table. It is formatted in the same way as normal data lines (value separated by the separator), but the meaning of the values is different: The first value in the headline is the name of the attribute where the first values in the following lines should go each time. Similarly, the second value in the headline is the name of the attribute for the second values in the following lines, and so on.

    这种格式用于解析以以下方式格式化的数据：基本上，每行由\emph{值}组成，它们由一个\emph{分隔符}分隔，如逗号或空格。值存储在不同的\emph{属性}中，即 |/data point| 的子键，如 |/data point/x|。为了决定为给定值选择哪个属性，标题很重要。这是表的第一个非空行。它的格式与普通数据行相同（值用分隔符分隔），但值的含义不同：标题中的第一个值是属性的名称，下面几行中的第一个值每次都应该在该属性中出现。类似地，标题中的第二个值是下面几行中第二个值的属性名，以此类推。

    % A simple example is the following:

    一个简单的例子如下：
    %
\begin{codeexample}[code only]
angle, radius
0, 1
45, 2
90, 3
135, 4
\end{codeexample}
    %
    % The headline states that the values in the first column should be stored in the |angle| attribute (|/data point/angle| to be precise) and that the values in the second column should be stored in the |radius| attribute. There are four data points in this data set.
    %
    标题声明，第一列中的值应该存储在 |angle| 属性中（确切地说是|/data point/angle|），第二列中的值应该存储在 |radius| 属性中。在这个数据集中有四个数据点。

    % The format will tolerate too few or too many values in a line. If there are less values in a line than in the headline, the last attributes will simply be empty. If there are more values in a line than in the headline, the values are stored in attributes called |/data point/attribute |\meta{column number}, where the first value of a line gets \meta{column number} equal to |1| and so on.

    这种格式可以在一行中容纳过少或过多的值。如果一行中的值比标题中的值少，最后的属性将为空。如果一行中的值比标题中的值多，则值存储在名为 |/data point/attribute|\meta{列号} 的属性中，其中一行的第一个值得到 \meta{列号} 等于 |1|，以此类推。

    % The |table| format can be configured using the following options:

    可以使用以下选项配置 |table| 格式：
    %
    \begin{key}{/pgf/data/separator=\meta{字符} (initially ,)} % \begin{key}{/pgf/data/separator=\meta{character} (initially ,)}
        % Use this key to change which character is used to separate values in the headline and in the data lines. To set the separator to a space, either set this key to an empty value or say |separator=\space|. Note that you must surround a comma by curly braces if you which to (re)set the separator character to a space.

        使用此键可更改用于分隔标题和数据行的值的字符。要将分隔符设置为空格，可以将此键设置为空值，或者说 |separator=\space|。注意，如果要（重新）将分隔符设置为空格，则必须用花括号将逗号括起来。
        %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
  \datavisualization [school book axes, visualize as line]
    data [separator=\space] {
      x y
      0 0
      1 1
      2 1
      3 0
    }
    data [separator=;] {
      x; y; z
      3; 1; 0
      2; 2; 0
    };
\end{tikzpicture}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/data/headline=\meta{首行}} % \begin{key}{/pgf/data/headline=\meta{headline}}
        % When this key is set to a non-empty value, the value of \meta{headline} is used as the headline and the first line of the data is treated as a normal line rather than as a headline.

        当此键被设置为非空值时，\meta{首行} 的值被用作标题，数据的第一行被视为正常行而不是标题。
        %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
  \datavisualization [school book axes, visualize as line]
    data [headline={x, y}] {
      0, 0
      1, 1
      2, 1
      3, 0
    };
\end{tikzpicture}
\end{codeexample}
    \end{key}
\end{dataformat}

\begin{dataformat}{named}
    % Basically, each line of the data must consist of a comma-separated sequence of attribute--values pairs like |x=5, lo=500|. This will cause the attribute |/data point/x| to be set to |5| and |/data point/lo| to be set to |500|.

    基本上，每一行数据必须由逗号分隔的属性值对序列组成，如 |x=5, lo=500|。这将导致属性 |/data point/x| 被设置为 |5| 以及 |/data point/lo| 被设置为 |500|。
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
  \datavisualization [school book axes, visualize as line]
    data [format=named] {
      x=0, y=0
      x=1, y=1
      x=2, y=1
      x=3, y=0
    };
\end{tikzpicture}
\end{codeexample}
    %
    % However, instead of just specifying a single value for an attribute as in |x=5|, you may also specify a whole set of values as in |x={1,2,3}|. In this case, three data points will be created, one for each value in the list. Indeed, the |\foreach| statement is used to iterate over the list of values, so you can write things like |x={1,...,5}|.
    %
    另外，与在 |x=5| 中只指定一个属性的单一值不同，您还可以指定一整套的值，如 |x={1,2,3}|。在本例中，将创建三个数据点，每个数据点对应列表中的每个值。实际上，|\foreach| 语句用于遍历值列表，因此您可以编写类似 |x={1,...,5}| 这样的内容。

    % It is also permissible to specify lists of values for more than one attribute. In this case, a data point is created for each possible combination of values in the different lists:

    还允许为多个属性指定值列表。在这种情况下，为不同列表中的每个可能的值组合创建一个数据点：
    %
\begin{codeexample}[
    width=7cm,
    preamble={\usetikzlibrary{datavisualization}},
]
\tikz \datavisualization
  [scientific axes=clean,
   visualize as scatter/.list={a,b,c},
   style sheet=cross marks]
data [format=named] {
  x=0,       y={1,2,3},        set=a
  x={2,3,4}, y={3,4,5,7},      set=b
  x=6,       y={5,7,...,15},   set=c
};
\end{codeexample}
    %
\end{dataformat}

\begin{dataformat}{TeX code}
    % This format will simply execute each line of the data, each of which should contain some normal TeX code. Note that at the end of each line control returns to the format handler, so for instance the arguments of a command may not be spread over several lines. However, not each line needs to produce a data point.

    这种格式将简单地执行数据的每一行，每一行应该包含一些普通的\TeX 代码。请注意，在每一行的末尾，控件返回到格式处理程序，因此，例如，命令的参数不能分布在多行中。然而，并不是每行都需要生成一个数据点。
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
  \datavisualization [school book axes, visualize as line]
    data [format=TeX code] {
      \pgfkeys{/data point/.cd,x=0, y=0} \pgfdatapoint
      \pgfkeys{/data point/.cd,x=1, y=1} \pgfdatapoint
      \pgfkeys{/data point/x=2}          \pgfdatapoint
      \pgfkeyssetvalue{/data point/x}{3}
      \pgfkeyssetvalue{/data point/y}{0} \pgfdatapoint
    };
\end{tikzpicture}
\end{codeexample}
    %
\end{dataformat}


% \subsection{Reference: Advanced Formats}
\subsection{参考：高级格式}

\begin{tikzlibrary}{datavisualization.formats.functions}
    % This library defines the formats described in the following, which allow you to specify the data points indirectly, namely via a to-be-evaluated function.

    这个库定义了下面描述的格式，允许您通过一个待求函数间接地指定数据点。

    \begin{dataformat}{function}
        % This format allows you to specify a function that is then evaluated in order to create the desired data points. In other words, the data lines do not contain the data itself, but rather a functional description of the data.

        该格式允许您指定一个函数，然后对其进行计算以创建所需的数据点。 换句话说，数据线不包含数据本身，而是数据的函数描述。

        % The format used to specify the function works as follows: Each nonempty line of the data should contain at least one of either a \emph{variable declaration} or a \emph{function declaration}. A variable declaration signals that a certain attribute will range over a given interval. The function declarations will then, later, be evaluated for values inside this interval. The syntax for a variable declaration is one of the following:

        用于指定函数的格式如下：数据的每个非空行应该至少包含\emph{变量声明}或\emph{函数声明}中的一个。变量声明表示某个属性将在给定间隔内变化。然后，函数声明将计算这个区间内的值。变量声明的语法如下所示：
        %
        \begin{enumerate}
            % \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|]| \opt{|samples |\meta{number}}|;|
            \item |var |\declare{\meta{变量}}| : interval[|\meta{最小值}|:|\meta{最大值}|]| \opt{|samples |\meta{数量}}|;|
            % \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|] step |\meta{step}|;|
            \item |var |\declare{\meta{变量}}| : interval[|\meta{最小值}|:|\meta{最大值}|] step |\meta{步长}|;|
            % \item |var |\declare{\meta{variable}}| : {|\meta{values}|};|
            \item |var |\declare{\meta{变量}}| : {|\meta{值列表}|};|
        \end{enumerate}
        %
        % In the first case, if the optional |samples| part is missing, the number of |samples| is taken from the value stored  in the following key:
        %
        在第一种情况下，如果可选的 |samples| 部分缺失，则 |samples| 的数量从以下键中存储的值中获取:
        %
        \begin{key}{/pgf/data/samples=\meta{数量} (initially 25)} % \begin{key}{/pgf/data/samples=\meta{number} (initially 25)}
            % Sets the number of samples to be used when no sample number is specified.

            设置未指定样本数量时要使用的样品数量。
        \end{key}
        %
        % The meaning of declaring a variable declaration to range over an |interval| is that the attribute named \meta{variable}, that is, the key |/data point/|\meta{variable}, will range over the interval $[\meta{low},\meta{high}]$. If the number of |samples| is given (directly or indirectly), the interval is evenly divided into \meta{number} many points and the attribute is set to each of these values. Similarly, when a \meta{step} is specified, this stepping is used to increase \meta{low} iteratively up to the largest value that is still less or equal to \meta{high}.
        %
        在|区间|上声明变量声明的意义是，名为 \meta{变量} 的属性，即关键的 |/data point/|\meta{变量}，将在区间$[\meta{最小值}, \meta{最大值}]$上声明。如果给定 |samples| 的数量（直接或间接），则将区间均匀划分为  \meta{数量} 个点，并为每个点设置属性。类似地，当指定 \meta{步长} 时，此步长用于迭代地增加 \meta{最小值}，迭代地增加到仍然小于或等于 \meta{最大值}。

        % The meaning of declaring a variable using a list of \meta{values} is that the variable will simply iterate over the values using |\foreach|.

        使用 \meta{值列表} 声明变量的意义是，该变量将使用 |\foreach| 简单地遍历这些值。

        % You can specify more than one variable. In this case, each variable is varied independently of the other variables. For instance, if you declare an $x$-variable to range over the interval $[0,1]$ in $25$ steps and you also declare a $y$-variable to range over the same interval, you get a total of $625$ value pairs.

        您可以指定多个变量。 在这种情况下，每个变量都独立于其他变量而变化。 例如，如果您以$25$的总步数在区间$[0,1]$的范围内声明$x$变量，并且还在同一区间的范围内声明$y$变量，则总计$625$个值对。

        % The variable declarations specify which (input) variables will take which values. It is the job of the \emph{function declarations} to specify how some additional attributes are to be computed. The syntax of a function declaration is as follows:

        变量声明指定哪个（输入）变量将接受哪个值。\emph{函数声明}的任务是指定如何计算一些附加属性值。函数声明的语法如下：
        %
        \begin{quote}
            % |func |\declare{\meta{attribute}}| = |\meta{expression}|;|

            |func |\declare{\meta{属性}}| = |\meta{表达式}|;|
        \end{quote}
        %
        % The meaning of such a declaration is the following: For each setting of the input variables (the variables specified using the |var| declaration), evaluate the \meta{expression} using the standard mathematical parser of \tikzname. The resulting value is then stored in |/data point/|\meta{attribute}.
        %
        这种声明的含义如下：对于输入变量（使用 |var| 声明指定的变量）的每个设置，使用\tikzname 的标准数学解析器计算 \meta{表达式}。结果存储在 |/data point/|\meta{属性} 中。

        % Inside \meta{expression} you can reference data point attributes using the following command, which is only defined inside such an expression:

        在 \meta{表达式} 的内部，您可以使用以下命令引用数据点属性，该命令只在这样的表达式内定义:
        %
        \begin{command}{\value\marg{变量}} % \begin{command}{\value\marg{variable}}
            % This expands to the current value of the key |/data point/|\meta{variable}.

            这会将当前值赋值给 |/data point/|\meta{变量} 键。
        \end{command}

        % There can be multiple function declarations in a single data specification. In this case, all of these functions will be evaluated for each setting of input variables.

        在一个数据指定中可以有多个函数声明。在本例中，所有这些函数都将针对每一组输入变量求值。
        %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\tikz
  \datavisualization [school book axes, visualize as smooth line]
    data [format=function] {
      var x : interval [-1.5:1.5];

      func y = \value x * \value x;
    };
\end{codeexample}
        %
\begin{codeexample}[
    width=6cm,
    preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\tikz \datavisualization [
  school book axes,
  all axes={unit length=5mm, ticks={step=2}},
  visualize as smooth line]
data [format=function] {
  var t : interval [0:2*pi];

  func x = \value t * cos(\value t r);
  func y = \value t * sin(\value t r);
};
\end{codeexample}
        %
\begin{codeexample}[
    width=7cm,
    preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\tikz \datavisualization [
  scientific axes=clean,
  y axis={ticks={style={
        /pgf/number format/fixed,
        /pgf/number format/fixed zerofill,
        /pgf/number format/precision=2}}},
  x axis={ticks={tick suffix=${}^\circ$}},
  visualize as smooth line/.list={1,2,3,4,5,6},
  style sheet=vary hue]
data [format=function] {
  var set : {1,...,6};
  var x : interval [0:50];
  func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
};
\end{codeexample}
    \end{dataformat}
\end{tikzlibrary}


% \subsection{Advanced: The Data Parsing Process}
\subsection{进阶：数据解析的过程}
\label{section-dv-parsing}

% Whenever data is fed to the data visualization system, it will be  handled by the |\pgfdata| command, declared in the |datavisualization| module. The command is both used to parse data stored in external sources (that is, in external files or which is produced on the fly by calling an external command) as well as data given inline. A data format does not need to know whether data comes from a file or is given inline, the |\pgfdata| command will take care of this.

当数据被提供给数据可视化系统时，它将被 |\pgfdata| 命令处理，该命令在 |datavisualization| 模块中声明。该命令既用于解析存储在外部源中的数据（即，在外部文件中或通过调用外部命令动态生成的数据），也用于解析给定的内联数据。数据格式不需要知道数据是来自文件还是以内联方式提供的，|\pgfdata| 命令会处理这个问题。

% Since \TeX\ will always read files in a line-wise fashion, data is always fed to data format parsers in such a fashion. Thus, even it would make more sense for a format to ignore line-breaks, the parser must still handle data given line-by-line.

因为\TeX\ 总是以行方式读取文件，所以数据总是以这种方式提供给数据格式解析器。因此，即使忽略换行符对格式更有意义，解析器仍然必须逐行处理给定的数据。

% Let us now have a look at how |\pgfdata| works.

现在让我们看看 |\pgfdata| 是如何工作的。

\begin{command}{\pgfdata\opt{\oarg{选项}\marg{内联数据}}} % \begin{command}{\pgfdata\opt{\oarg{options}\marg{inline data}}}
    % This command is used to feed data to the visualization pipeline. This command can only be used when a data visualization object has been properly setup, see Section~\ref{section-dv-main-setup}.

    此命令用于向可视化管道提供数据。此命令只能在正确设置数据可视化对象时使用，请参阅第\ref{section-dv-main-setup}节。

    \medskip
    % \textbf{Basic options.} The |\pgfdata| command may be followed by \meta{options}, which are executed with the path |/pgf/data/|. Depending on these options, the \meta{options} may either be followed by \meta{inline data} or, alternatively, no \meta{inline data} is present and the data is read from an external source.

    \textbf{基本选项。} 在 |\pgfdata| 命令后面可能跟着 \meta{选项}，它们以 |/pgf/data/| 路径执行。根据这些选项，\meta{选项} 后面可能跟着 \meta{内联数据}，或者也可能没有 \meta{内联数据}，数据是从外部源读取的。

    % The first important option is \meta{source}, which governs which of these two alternatives applies:

    第一个重要的选项是 \meta{源}，它管理这两个选项中的哪一个适用:
    %
    \begin{key}{/pgf/data/read from file=\meta{文件名} (initially \normalfont empty)} % \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
        % If you set the |read from file| attribute to a non-empty \meta{filename}, the data will be read from this file. In this case, no \meta{inline data} may be present, not even empty curly braces should be provided. If |read from file| is empty, the  data must directly follow as \meta{inline data}.

        如果将 |read from file| 属性设置为一个非空 \meta{文件名}，则将从该文件读取数据。在这种情况下，可能不存在 \meta{内联数据}，甚至不应该提供空花括号。如果 |read from file| 属性为空，则数据必须以 \meta{内联数据} 的方式给出。
        %
\begin{codeexample}[code only]
% Data is read from two external files:
\pgfdata[format=table, read from file=file1.csv]
\pgfdata[format=table, read from file=file2.csv]
\end{codeexample}
        %
\begin{codeexample}[code only]
% Data is given inline:
\pgfdata[format=table]
{
  x, y
  1, 2
  2, 3
}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/data/inline}
        % This is a shorthand file |read from file={}|. You can add this to make it clear(er) to the reader that data follows inline.

        这是 |read from file={}| 的简写形式。您可以添加它，以便让读者明白数据是内联的。
    \end{key}
    %
    % The second important key is |format|, which is used to specify the data format:
    %
    第二个重要的键是 |format|，用于指定数据格式:
    %
    \begin{key}{/pgf/data/format=\meta{格式} (initially table)} % \begin{key}{/pgf/data/format=\meta{format} (initially table)}
        % Use this key to locally set the format used for parsing the data. The \meta{format} must be a format that has been previously declared using the |\pgfdeclaredataformat| command. See the reference section for a list of the predefined formats.

        使用此键可在本地设置用于解析数据的格式。\meta{格式} 必须是之前使用 |\pgfdeclaredataformat| 命令声明的格式。有关预定义格式的列表，请参阅参考部分。
    \end{key}
    %
    % In case all your data is in a certain format, you may wish to generally set the above key somewhere at the beginning of your file. Alternatively, you can use the following style to setup the |format| key and possibly further keys concerning the data format:
    %
    如果你所有的数据都是某种格式的，你可能希望在你的文件开始的地方设置上面的键。或者，您可以使用以下样式来设置 |format| 键，以及可能涉及数据格式的其他键：
    %
    \begin{stylekey}{/pgf/every data}
        % This style is executed by |\pgfdata| before the \meta{options} are parsed.

        此样式由 |\pgfdata| 在解析 \meta{选项} 之前执行。

        % Note that the path of this key is just |/pgf/|, not |/pgf/data/|. Also note that \tikzname\ internally sets the value of this key up in such a way that the keys |/tikz/every data| and also |/tikz/data visualization/every data| are executed. The bottom line of this is that when using \tikzname, you should not set this key directly, set |/tikz/every data| instead.

        注意，这个键的路径只是 |/pgf/|，而不是 |/pgf/data/|。还请注意，\tikzname\ 在内部设置此键的值，使键 |/tikz/every data| 以及 |/tikz/data visualization/every data| 执行。结果是，当使用\tikzname 时，您不应该直接设置该键，而是设置 |/tikz/every data|。
    \end{stylekey}

    \medskip
    % \textbf{Gathering of the data.} Once the data format and the source have been decided upon, the data is ``gathered''. During this phase the data is not actually parsed in detail, but just gathered so that it can later be parsed during the visualization. There are two different ways in which the data is gathered:

    \textbf{数据的收集。} 一旦确定了数据格式和来源，就开始``收集''数据。在此阶段，数据并没有被实际详细解析，而是被收集起来，以便稍后在可视化过程中对其进行解析。收集数据有两种不同的方式：
    %
    \begin{itemize}
        % \item In case you have specified an external source, the data visualization object is told (by means of invoking the |add data| method) that it should (later) read data from  the file specified by the |source| key using the format specified by the |format| key. The file is not read at this point, but only later during the actual visualization.
        \item 如果您指定了一个外部源，数据可视化对象被告知（通过调用|add data|方法）它应该（稍后）使用 |format| 键指定的格式从 |source| 键指定的文件中读取数据。该文件不是在此时读取，而是在稍后实际的可视化过程中读取。
        % \item Otherwise, namely when data is given inline, depending on which format is used, some catcodes get changed. This is necessary since \TeX's special characters are often not-so-special in a certain format.
        \item 否则，即当数据以内联方式给出时，根据使用的格式，一些类别代码会发生变化。这是必要的，因为\TeX 的特殊字符在某种格式中通常并不特别。

            % Independently of the format, the end-of-line character (carriage return) is made an active character.

            独立于格式，将行尾字符（回车）设置为活动字符。

            % Finally, the \meta{inline data} is then read as a normal argument and the data visualization object is told that later on it should parse this data using the given format parser. Note that in this case the data visualization object must store the whole data internally.

            最后，将 \meta{内联数据} 作为一个普通参数读取，并告知数据可视化对象稍后应该使用给定的格式解析器解析该数据。注意，在这种情况下，数据可视化对象必须在内部存储整个数据。
    \end{itemize}
    %
    % In both cases the ``data visualization object'' is the object stored in the |/pgf/data visualization/obj| key.
    %
    在这两种情况下，``数据可视化对象''都是存储在 |/pgf/data visualization/obj| 键中的对象。


    \medskip
    % \textbf{Parsing of the data.} During the actual data visualization, all code that has been added to the data visualization object by means of the |add data| method is executed several times. It is the job of this code to call the |\pgfdatapoint| method for all data points present in the data.

    \textbf{数据解析。} 在实际的数据可视化过程中，所有通过 |add data| 的方法添加到数据可视化对象中的代码都会执行多次。这段代码的任务是为数据中出现的所有数据点调用 |\pgfdatapoint| 方法。

    % When the |\pgfdata| method calls |add data|, the code that is passed to the data visualization object is just a call to internal macros of |\pgfdata|, which are able to parse the data stored in an external file or in the inlined data. Independently of where the data is stored, these macros always do the following:

    当 |\pgfdata| 方法调用 |add data| 时，传递给数据可视化对象的代码只是对 |\pgfdata| 的内部宏的调用，该宏能够解析存储在外部文件或内联数据中的数据。独立于数据存储的地方，这些宏总是做以下事情:
    %
    \begin{enumerate}
        % \item The catcodes are setup according to what the data format requires.
        \item 根据数据格式的要求设置类别代码。
        % \item Format-specific startup code gets called, which can initialize internal variables of the parsing process. (The catcode changes are not part of the startup code since in order to read inline data |\pgfdata| must be able to setup to temporarily setup the catcodes needed later on by the parsers, but since no reading is to be done, no startup code should be called at this point.)
        \item 调用特定格式的启动代码，它可以初始化解析过程的内部变量。（类别代码变化不是启动代码的一部分，因为为了读取内联数据 |\pgfdata| 必须能够设置临时设置类别代码以提供给后来的解析器，但是因为没有读取数据，在这一点上可以说没有启动代码）。
        % \item For each line of the data a format-specific code handler, which depends on the data format, is called. This handler gets the current line as input and should call |\pgfdatapoint| once for each data point that is encoded by this line (a line might define multiple data points or none at all). Empty lines are handled by special format-specific code.
        \item 对于数据的每一行，将调用一个特定于格式的代码处理程序，该处理程序取决于数据格式。此处理程序获取作为输入的当前行，并且应该对该行编码的每个数据点调用 |\pgfdatapoint| 一次（一行可能定义多个数据点，也可能根本没有定义）。空行由特定格式的代码处理。
        % \item At the end, format-specific end code is executed.
        \item 最后，执行特定格式的结束代码。
    \end{enumerate}
    %
    % For an example of how this works, see the description of the |\pgfdeclaredataformat| command.
    %
    有关其工作原理的示例，请参见 |\pgfdeclaredataformat| 命令的描述。


    \medskip
    % \textbf{Data sets.} There are three options that allow you to create \emph{data sets}. Such a data set is essentially a macro that stores a pre-parsed set of data that can be used multiple times in subsequent visualizations (or even in the same visualization).

    \textbf{数据集。} 有三个选项允许您创建\emph{数据集}。这样的数据集本质上是一个宏，它存储一组可在后续可视化（甚至在同一可视化）中多次使用的预解析数据。
    %
    \begin{key}{/pgf/data/new set=\meta{数据集名称}} % \begin{key}{/pgf/data/new set=\meta{name}}
        % Creates an empty data set called \meta{name}. If a data set of the same name already exists, it is overwritten and made empty. Data sets are global.

        创建一个名为 \meta{数据集名称} 的空数据集。如果相同名称的数据集已经存在，则覆盖该数据集并使其为空。数据集是全局的。
    \end{key}
    %
    \begin{key}{/pgf/data/store in set=\meta{数据集名称}} % \begin{key}{/pgf/data/store in set=\meta{name}}
        % When this key is set to any non-empty \meta{name} and if this \meta{name} has previously been used with the |new set| key, then the following happens: For the current |\pgfdata| command, all parsed data is not passed to the rendering pipeline. Instead, the parsed data is appended to the data set \meta{name}. This includes all options parsed to the |\pgfdata| command, which is why neither this key nor the previous key should be passed as options to a |\pgfdata| command.

        当此键被设置为任何非空的 \meta{数据集名称}，并且如果此 \meta{数据集名称} 以前已与 |new set| 键一起使用，则会发生以下情况：对于当前 |\pgfdata| 命令，所有解析后的数据都不会传递给渲染管道。相反，解析后的数据被附加到名为 \meta{数据集名称} 的数据集中。这包括解析 |\pgfdata| 命令的所有选项，这就是为什么这个键和之前的键都不应该作为选项传递给 |\pgfdata| 命令。
    \end{key}
    %
    \begin{key}{/pgf/data/use set=\meta{数据集名称}} % \begin{key}{/pgf/data/use set=\meta{name}}
        % This works similar to |read from file|. When this key is used with a |\pgfdata| command, no inline data may follow. Instead, the data stored in the data set \meta{name} is used.

        它的工作原理类似于 |read from file|。当此键与 |\pgfdata| 命令一起使用时，可能不会紧跟内联数据。而是使用存储在数据集 \meta{数据集名称} 中的数据。
    \end{key}
\end{command}


% \subsection{Advanced: Defining New Formats}
\subsection{进阶：创建新格式}
\label{section-dv-declaring-formats}

% In order to define a new data format you can use the following command, which is basic layer command defined in the module |datavisualization|:

为了定义一个新的数据格式，您可以使用以下命令，这是在模块 |datavisualization| 中定义的基本层命令：

\newlength{\length}
\settowidth{\length}{pgfdeclaredataformat}
\begin{command}{\pgfdeclaredataformat\parbox[t]{0.7\textwidth}{\marg{格式名称}\marg{类别代码}\marg{启动代码}\marg{行参数}\\\hspace{\length}\marg{行处理代码}\marg{空行处理代码}\marg{结束代码}}} % \begin{command}{\pgfdeclaredataformat\marg{format name}\marg{catcode code}\marg{startup code}\marg{line arguments}\\\marg{line code}\marg{empty line code}\marg{end code}}
    % This command defines a new data format called \meta{format name}, which can subsequently be used in the |\pgfdata| command. (The \tikzname's |data| maps directly to |\pgfdata|, so the following applies to \tikzname\ as well.)

    此命令定义了一个名为 \meta{格式名称} 的新数据格式，该格式可随后在 |\pgfdata| 命令中使用。（\tikzname 的 |data| 直接映射到 |\pgfdata|，因此下面的内容也适用于\tikzname\ ）。

    % As explained in the description of the |\pgfdata| command, when data is being parsed that is formatted according to \meta{format name}, the following happens:

    正如在 |\pgfdata| 命令的描述中所解释的，当根据名为 \meta{格式名称} 格式的数据被解析时，会发生以下情况:
    %
    \begin{enumerate}
        % \item The \meta{catcode code} is executed. This code should just contain catcode changes. The \meta{catcode code} will also be executed when inline data is read.
        \item 执行 \meta{类别代码}。此代码应该只包含类别的更改。当读取内联数据时，\meta{类别代码} 也将执行。
        % \item Next, the \meta{startup code} is executed.
        \item 接下来，执行 \meta{启动代码。}
        % \item Next, for each non-empty line of the data, the line is passed to a macro whose argument list is given by \meta{line arguments} and whose body is given by \meta{line code}. The idea is that you can use \TeX's powerful pattern matching capabilities to parse the non-empty lines. See also the below example.
        \item 接下来，对于数据的每一个非空行，该行被传递到一个宏，该宏的参数列表由 \meta{行参数} 给出，其主体由 \meta{行处理代码} 给出。其思想是可以使用\TeX 强大的模式匹配功能来解析非空行。参见下面的示例。
        % \item Empty lines are not processed by the \meta{line code}, but rather by the \meta{empty line code}. Typically, empty lines can simply be ignored and in this case you can let this parameter be empty.
        \item 空行不是由 \meta{行处理代码} 处理，而是由 \meta{空行处理代码} 处理。通常，可以简单地忽略空行，在这种情况下，您可以让这个参数为空。
        % \item At the end of the data, the \meta{end code} is executed.
        \item 在数据的末尾，执行 \meta{结束代码}。
    \end{enumerate}

    % As an example, let us now define a simple data format for reading files formatted in the following manner: Each line should contain a coordinate pair as in |(1.2,3.2)|, so two numbers separated by a comma and surrounded by parentheses. To make things more interesting, suppose that the hash mark symbol can be used to indicate comments. Here is an example of some data given in this format:

    作为示例，现在让我们定义一种简单的数据格式，用于读取格式化为以下方式的文件:每一行应该包含一个坐标对，如 |(1.2,3.2)| 中所示，即两个用逗号分隔并由括号包围的数字。为了使事情更有趣，假设可以使用散列标示符号（\#号）来表示注释。以下是一些以这种格式给出的数据的例子：
    %
\begin{codeexample}[code only]
# This is some data formatted according to the "coordinates" format
(0,0)
(0.5,0.25)
(1,1)
(1.5,2.25)
(2,4)
\end{codeexample}

    % A format parser for this format could be defined as follows:

    可以如下定义该格式的格式解析器：
    %
\begin{codeexample}[code only]
\pgfdeclaredataformat{coordinates}
% First comes the catcode argument. We turn the hash mark into a comment character.
{\catcode`\#=14\relax}
% Second comes the startup code. Since we do not need to setup things, we can leave
% it empty. Note that we could also set it to something like \begingroup, provided we
% put an \endgroup in the end code
{}
% Now comes the arguments for non-empty lines. Well, these should be of the form
% (#1,#2), so we specify that:
{(#1,#2)}
% Now we must do something with a line of this form. We store the #1 argument in
% /data point/x and #2 in /data point/y. Then we call \pgfdatapoint to create a data point.
{
  \pgfkeyssetvalue{/data point/x}{#1}
  \pgfkeyssetvalue{/data point/y}{#2}
  \pgfdatapoint
}
% We ignore empty lines:
{}
% And we also have no end-of-line code.
{}
\end{codeexample}
    %
    % This format could now be used as follows:

    现在可以使用以下格式：
    %
\begin{codeexample}[code only]
\begin{tikzpicture}
  \datavisualization[school book axes, visualize as smooth line]
  data [format=coordinates] {
    # This is some data formatted according
    # to the "coordinates" format
    (0,0)
    (0.5,0.25)
    (1,1)
    (1.5,2.25)
    (2,4)
  };
\end{tikzpicture}
\end{codeexample}
    %
\end{command}


